API Documentation

The Tinylytics API provides programmatic access to your analytics data. Perfect for building custom dashboards, integrations, or automated reporting.

Quick Start

Base URL: https://tinylytics.app/api/v1/

Authentication: Include your API key in the Authorization header:

Authorization: Bearer tly-ro-your-api-key-here

Get an API Key: Account Settings → API Access → Create New API Key

API Endpoints

Quick Navigation

• Account & Sites
  • Test API Key
  • List Sites
  • Site Details
• Analytics
  • Site Hits
  • Leaderboard
  • User Journeys
  • Insights
• Monitoring
  • Uptime Status

Account & Sites

GET /me

Test your API key and get account information.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/me

Example Response

{
  "user": {
    "email": "[email protected]",
    "name": "John Doe",
    "subscription_status": "active",
    "sites_count": 5
  }
}

GET /sites

List all your sites.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites

Example Response

{
  "sites": [
    {
      "id": 456,
      "uid": "abc123",
      "url": "https://example.com",
      "label": "My Blog",
      "lifetime_hits": 12345,
      "active": true
    },
    {
      "id": 457,
      "uid": "def456",
      "url": "https://another-site.com",
      "label": "Another Site",
      "lifetime_hits": 6789,
      "active": true
    }
  ],
  "total_count": 2
}

GET /sites/:id

Get details for a specific site.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites/456

Example Response

{
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog",
    "lifetime_hits": 12345,
    "lifetime_unique_hits": 8901,
    "active": true,
    "is_public": false,
    "created_at": "2023-01-15T10:00:00Z",
    "updated_at": "2023-06-04T14:22:00Z"
  }
}

Analytics

GET /sites/:id/hits

Get analytics data for a site with filtering and grouping options.

Parameters

• start_date / end_date - Date range (YYYY-MM-DD, max 365 days)
• country - Filter by country code (e.g., “US”, “GB”)
• path - Filter by exact path (e.g., “/blog/post”)
• referrer - Filter by referrer (partial match)
• grouped=true - Return aggregated data
• group_by - Group by: path, country, referrer, browsername, platformname
• page / per_page - Pagination (max 1000 per page)

Example Requests

Basic Analytics

# Last 7 days of hits
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?start_date=2023-05-28&end_date=2023-06-04"

# Filter by country and path
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?country=US&path=/blog"

Grouped Analytics

# Most popular pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=path"

# Top traffic sources
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=referrer"

Example Response (Individual Hits)

{
  "hits": [
    {
      "id": 789012,
      "url": "https://example.com/blog/my-post",
      "path": "/blog/my-post",
      "referrer": "https://twitter.com",
      "country": "US",
      "browser_name": "Chrome",
      "platform_name": "macOS",
      "is_mobile": false,
      "created_at": "2023-06-04T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 1547,
    "total_pages": 16
  }
}

Example Response (Grouped Data)

{
  "grouped_hits": [
    {
      "path": "/blog/popular-post",
      "hit_count": 247
    },
    {
      "path": "/",
      "hit_count": 156
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 25,
    "total_pages": 1
  }
}

GET /sites/:id/leaderboard

Get a leaderboard of all paths for a site, ranked by total hits with caching for performance.

Parameters

• path - Filter paths containing this term (case-insensitive, partial match)
• page / per_page - Pagination (max 1000 per page)

Features

• Returns all-time data (no date filtering)
• Includes total hits, unique hits, and percentage of site traffic
• 1-hour caching for optimal performance
• Separate cache for filtered vs unfiltered results

Example Requests

# All-time top pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard"

# Filter blog posts only
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard?path=blog"

Example Response

{
  "leaderboard": [
    {
      "path": "/blog/popular-post",
      "total_hits": 1250,
      "unique_hits": 890,
      "percentage": 15.2
    },
    {
      "path": "/about",
      "total_hits": 800,
      "unique_hits": 650,
      "percentage": 9.7
    }
  ],
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog"
  },
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 245,
    "total_pages": 3
  },
  "cache_info": {
    "cached_at": "2024-01-01T12:00:00Z",
    "expires_at": "2024-01-01T13:00:00Z"
  },
  "filters": {
    "path": "blog"
  }
}

GET /sites/:id/user_journeys

Analyze visitor behavior and user journeys through your site. Track how users navigate between pages, identify popular entry/exit points, and measure engagement patterns.

Parameters

• start_date / end_date - Date range (YYYY-MM-DD, max 365 days, defaults to last 30 days)
• page / per_page - Pagination (max 50 per page for journeys)

Features

• Complete visitor journey paths with timestamps
• Session duration calculations
• Bounce rate analysis (single-page vs multi-page visitors)
• Top entry and exit pages identification
• Privacy-preserving visitor identification
• Real-time data (no caching for accurate journey tracking)

Example Requests

# Visitor journeys for last 30 days
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/user_journeys"

# Custom date range
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/user_journeys?start_date=2024-01-01&end_date=2024-01-31"

Example Response

{
  "user_journeys": [
    {
      "visitor_hash": "a1b2c3d4e5f6",
      "page_count": 4,
      "pages": [
        {
          "path": "/",
          "visited_at": "2024-01-15T10:00:00Z"
        },
        {
          "path": "/blog",
          "visited_at": "2024-01-15T10:02:30Z"
        },
        {
          "path": "/blog/user-journeys",
          "visited_at": "2024-01-15T10:05:15Z"
        },
        {
          "path": "/contact",
          "visited_at": "2024-01-15T10:08:45Z"
        }
      ],
      "entry_page": "/",
      "exit_page": "/contact",
      "session_duration": "8m"
    }
  ],
  "summary": {
    "total_visitors": 1247,
    "multi_page_visitors": 456,
    "single_page_visitors": 791,
    "bounce_rate": 63.4
  },
  "insights": {
    "top_entry_pages": [
      {
        "path": "/",
        "visitors": 634
      },
      {
        "path": "/blog",
        "visitors": 289
      },
      {
        "path": "/about",
        "visitors": 156
      }
    ],
    "top_exit_pages": [
      {
        "path": "/contact",
        "visitors": 234
      },
      {
        "path": "/",
        "visitors": 198
      },
      {
        "path": "/blog/popular-post",
        "visitors": 123
      }
    ]
  },
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_count": 456,
    "total_pages": 46
  },
  "filters": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

GET /sites/:id/insights

Get AI-powered insights and recommendations for your site. Access traffic patterns analysis, best performing content identification, and actionable recommendations to improve your website.

Parameters

• page / per_page - Pagination (max 50 per page)

Features

• AI-generated insights based on your site’s analytics data
• Traffic pattern analysis and trend identification
• Best performing content recommendations
• Actionable suggestions to improve engagement
• Historical insights with formatted dates
• Site configuration status (insights enabled, daily reports)
• Next insight job scheduling information

Example Requests

# Get recent insights for a site
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/insights"

# Paginated insights
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/insights?page=2&per_page=5"

Example Response

{
  "insights": [
    {
      "id": 116,
      "insights_for_date": "2025-10-16",
      "formatted_insights_date": "October 16, 2025",
      "generated_at": "2025-10-16T08:20:27.902Z",
      "traffic_patterns": "Your site's traffic is spreading out nicely this week, with Sunday taking the lead at 47 hits and a nice bump around 2:00 PM bringing in 20 visitors—perfect for that afternoon crowd. It's a welcome change from those quiet Friday evenings we saw before, showing more folks are discovering you throughout the week, especially weekends and early in the day. Overall, with 250 hits from 235 unique visitors, things feel more lively, even if it's a bit down from last week—still a huge step up from 70 hits a month ago!",
      "best_content": "The pricing page is shining brightest with 36 hits, closely followed by contact at 33 and your homepage at 33—looks like people are curious about what you offer and how to reach out. Products and blog are close behind at 29 and 28, gaining some real traction since last month when homepage and docs were the main draws. This suggests visitors are moving beyond just browsing to exploring options and connecting, which is a positive sign of deeper interest. Chrome leads the browsers at about 42%, so keeping things crisp there will help everyone enjoy the site.",
      "recommendations": "With pricing and contact pages drawing so much attention, try adding a friendly FAQ section to those pages to answer common questions right away and keep visitors engaged longer. Since Sunday afternoons are buzzing, consider timing any fresh updates or blog posts around then to catch that wave. And hey, your traffic's grown over three times since last month—keep nurturing that international mix from places like Poland and France with simple, universal language on your key pages."
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_count": 1,
    "total_pages": 1
  },
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog",
    "insights_enabled": true,
    "daily_insight_reports_active": false,
    "next_insight_job_scheduled_at": "2025-10-25T01:00:00Z"
  }
}

Response Fields

Insight Object:

• id - Unique identifier for the insight
• insights_for_date - Date the insight was generated for (YYYY-MM-DD)
• formatted_insights_date - Human-readable date format
• generated_at - Timestamp when the insight was created
• traffic_patterns - Analysis of traffic trends and patterns
• best_content - Identification of top performing pages/content
• recommendations - Actionable suggestions to improve site performance

Site Object:

• id - Site identifier
• uid - Unique site identifier for public access
• url - Site URL
• label - Site display name
• insights_enabled - Whether AI insights are enabled for this site
• daily_insight_reports_active - Whether daily insight email reports are enabled
• next_insight_job_scheduled_at - When the next insight generation job is scheduled (null if disabled)

Monitoring

GET /sites/:id/uptime

Monitor website uptime, SSL certificate status, and domain information. Track downtime incidents, SSL certificate expiration, domain expiry, and more.

Parameters

• page / per_page - Pagination for downtimes (max 50 per page)

Features

• Real-time uptime percentage and monitoring status
• Downtime history with duration and error details
• SSL certificate validation and expiration tracking
• Domain registration monitoring and expiry tracking
• Current check intervals and monitoring configuration
• Automatic pause detection for extended outages
• Human-readable duration formatting

Example Requests

# Get uptime status and recent downtimes
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/uptime"

# Paginated downtime history
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/uptime?page=2&per_page=25"

Example Response

{
  "monitor": {
    "id": 33,
    "url": "https://example.com",
    "enabled": true,
    "is_down": true,
    "uptime": "98.95",
    "last_check_at": "2025-08-02T20:45:47.000Z",
    "next_check_at": "2025-08-02T20:50:44.000Z",
    "last_status_code": 530,
    "last_error_message": "530 Custom Cloudflare Error",
    "status_description": "Server Error (530)",
    "current_check_interval": "5 minutes",
    "period": 300,
    "ssl": {
      "expires_at": "2025-09-08T19:29:06.000Z",
      "valid": true,
      "expiring_soon": false,
      "expired": false,
      "days_until_expiry": 36
    },
    "domain": {
      "tested_at": "2025-08-01T12:00:00.000Z",
      "expires_at": "2026-03-15T00:00:00.000Z",
      "remaining_days": 195,
      "source": "whois",
      "expired": false,
      "expiring_soon": false,
      "days_until_expiry": 195
    },
    "auto_paused": false,
    "created_at": "2025-03-29T14:50:30.509Z",
    "updated_at": "2025-08-02T20:47:10.966Z"
  },
  "downtimes": [
    {
      "id": 1,
      "error": "530 Custom Cloudflare Error",
      "started_at": "2025-03-30T18:22:07.000Z",
      "ended_at": "2025-05-22T19:26:19.000Z",
      "duration": 4583052,
      "duration_in_words": "53 days",
      "partial": false,
      "ongoing": false
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total_count": 8,
    "total_pages": 1
  },
  "summary": {
    "total_downtimes": 8,
    "ongoing_downtimes": 0,
    "recent_downtimes_30_days": 0
  }
}

Common Use Cases

Custom Dashboard: Combine /sites and /sites/:id/hits to build analytics dashboards

Traffic Monitoring: Fetch daily hits and compare against historical data for automated alerts

Content Analysis: Use grouped data to identify popular pages, top referrers, and audience demographics

Performance Insights: Group by browser, platform, or country for technical and geographic analytics

Top Content Discovery: Use /sites/:id/leaderboard to find your most popular content across all time

Content Strategy: Filter leaderboard by path segments (e.g., “/blog”, “/product”) to analyze specific content types

User Journey Analysis: Use /sites/:id/user_journeys to understand visitor behavior patterns:

• Identify drop-off points in conversion funnels
• Optimize navigation by analyzing common user paths
• Measure engagement through session duration and bounce rates
• Discover how users discover and consume your content
• A/B test page flows by comparing journey patterns over time

AI-Powered Insights: Use /sites/:id/insights to get automated analysis and recommendations:

• Receive AI-generated traffic pattern analysis and trend identification
• Discover your best performing content without manual analysis
• Get actionable recommendations to improve user engagement
• Track insight generation schedule and email report settings
• Monitor historical insights to track progress over time
• Integrate AI recommendations into your content strategy and site optimization

Uptime Monitoring: Use /sites/:id/uptime to monitor site availability and performance:

• Track real-time uptime percentage and current status
• Analyze downtime patterns and error types
• Monitor SSL certificate expiration and validity
• Track domain registration expiry and renewal reminders
• Set up automated alerts based on uptime thresholds
• Review historical downtime incidents for root cause analysis
• Integrate with status pages and incident management systems

Error Handling

Error Response:

{
  "error": "API access requires an active subscription"
}

Rate Limits

API requests are subject to reasonable rate limits. If exceeded, you’ll receive a 429 status code.

Need Help?

Contact us at [email protected] for API questions or implementation assistance. We aim to respond within 24 hours.